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III. FORMATTING FACILITIES 
NROFF AND TROFF USER’S MANUAL . 
1. Introduction 


Text processors, nroff and troff, under the UNIX operating system format text for typewriter-like termi- 
nals and for a phototypesetter, respectively. Both nroff and troff processors accept lines of text interspersed 
with lines of format control information. They format the text into a printable, paginated document having a 
user-designed style. The nroff and troff formatters offer unusual freedom in document styling including: 


e Arbitrary style headers and footers 

e Arbitrary style footnotes 

e Multiple automatic sequence numbering for paragraphs and satvions 
e Multiple column output 

e Dynamic font and point-size control 

e Arbitrary horizontal and vertical local motions at any point 

e Overstriking, bracket construction, and line drawing functions. 


Since nroff and troff formatters are reasonably compatible, it is usually possible to prepare input accept- 
able to both. Conditional input is provided that enables the user to embed input expressly destined for either 
program. The nroff formatter can prepare output directly for a variety of terminal types and is capable of uti- 
lizing the full resolution of each terminal. 


The troff processor is a text-formatting program for driving a phototypesetter on the UNIX operating sys- 
tem. It is capable of producing high quality text. The phototypesetter normally runs with four fonts containing 
Roman, italic, and bold letters; a full Greek alphabet; a substantial number of special characters; and mathe- 
matical symbols. Characters can be printed in a range of sizes and placed anywhere on the page. 


Full user control over fonts, sizes, and character positions, as well as the usual features of a formatter 
(right-margin justification, automatic hyphenation, page titling and numbering, etc.) are provided by the troff 
processor. It also provides macros, arithmetic variables and operations, and conditional testing for complicated 
formatting tasks. 


2. Usage 


The general form of invoking an nroff or troff formatter at the UNIX operating system command level 
is 


nroff options files 
or 
troff options files 


where options represents any of a number of option arguments and files represents the list of files containing 
the document to be formatted. An argument consisting of a single minus sign (— ) is taken to be a file name corre- 
sponding to the standard input. Input is taken from the standard input if no file names are given. Options may 
appear in any order so long as they appear before the files. 
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OPTION 


—olist 


—nN 


—sN 


—mname 


~cname 
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nroff and troff 
EFFECT 


Prints only pages whose page numbers appear in list, which consists of comma-separated 
numbers and number ranges. 


e A number range has the form N-M and means pages N through M 

e An initial -N means from the beginning to page N 

e A final N- means from page N to the end. 

Number the first generated page N. 

Stop every N page (and cause the bell control character to be output to the terminal). The 
nroff formatter will halt after every N pages (default N=1) to allow paper loading or 
changing and will resume upon receipt of a new line. The troff formatter will stop the 
phototypesetter every N pages, produce a trailer to allow changing cassettes, and resume 
after the phototypesetter START button is pressed. 

Prepend the macro file 


/usr/lib/tmac/tmac.name 


to the input files. Multiple -m macro package requests on a command line are accepted 
and are processed in sequence. 


Prepend the macro files 


/usr/lib/macros/cmp.[nt].[dt].name 
and 
/usr/lib/macros/ucmp,[nt].name 


to the input files. Multiple —e macro package requests on a command line are accepted. 
The compacted version of macro package name should be used if it exists. If not, the 
nroff/troff formatter will try the equivalent —mname option instead. This option should 
be used instead of —m because it makes the nroff/troff formatters execute significantly 
faster. 


Set register a (one character) to N. 
Read standard input after the input files are exhausted. 
Invoke the simultaneous input/output mode of the rd request. 


Suppress formatted output. Only message output will occur (from tm requests and diag- 
nostics). 


Produce a compacted macro package from this invocation of the nroff/troff formatter. 
This option has no effect if no .co request is used in the nroff/troff formatter input. Oth- 
erwise, the compacted output is produced in files d.name and t.namie. 
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nroff Only 


OPTION EFFECT 


—T name Specify the name of the output terminal type. Currently defined names are: 37 (default) 
for the TELETYPE Model 37, tn300 for the GE TermiNet 300 (or any terminal without 
half-line capabilities), 300 for the DASI 300, 300s for the DASI 300s, and 450 for the 


e& DASI 450. 
—-e Produce equally spaced words in adjusted lines using full terminal resolution. 
—h Use output tabs during horizontal spacing to speed output and to reduce output byte count. 


Device tab settings are assumed to be every eight nominal character widths. The default 
settings of logical input tabs are also every eight nominal character widths. 


& —un Set the emboldening factor (number of character overstrikes) in the nroff formatter for 
the third font position (bold) to be n (zero if nis missing). 
troff Only 
OPTION EFFECT 

= Direct output to the standard output instead of the phototypesetter. 

=f Refrain from feeding paper and stopping phototypesetter at the end of the run. 

—w Wait until phototypesetter is available if busy. 
& —b Report whether phototypesetter is busy or available. No text processing is done. 

= Send a printable approximation in American Standard Code for Information Interchange 


(ASCII) character set of the results to the standard output. This approximates a display 
of the document. 


—pN Print all characters in point size N while retaining all prescribed spacings and motions to 
reduce phototypesetter elapsed time. 


—# Prepare output for the Murray Hill Computation Center phototypesetter and direct it to 
the standard output. 


Each option is invoked as a separate argument. For example: 
2 rnoff —o04,8-10 —T300s —mabe filel file2 


requests formatting of pages 4, 8, 9, and 10 of a document contained in the files named filel and file2, specifies 
the output terminal as a DASI 300s, and invokes the macro package abe. 


Various preprocessors and postprocessors are available for use with the nroff and troff formatters: 
& e The equation preprocessors are neqn and eqn (for nroff and troff formatters, respectively). 
e The table-construction preprocessor is tbl. 
e A reverse-line postprocessor for multiple-column nroff formatter output on terminals without reverse- 


line ability is col. The TELETYPE Model 37 escape sequences that the nroff formatter produces by de- 
e fault are expected by col. 
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e The TELETYPE Model 37-simulator postprocessor for printing nroff formatter output on a Tektronix 
4014 is 4014. 


e The phototypesetter-simulator postprocessor for the troff formatter that produces an approximation 
of phototypesetter output on a Tektronix 4014 is te. For example, in 


tbl files | eqn i troff -t [options] | te 


the first ! indicates the piping of tbl output to eqn input; the second | indicates the piping of eqn 
output to the troff formatter input; and the third | indicates the piping of the troff formatter 
output to file te 
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3. NROFF/TROFF Reference Manual 
3.1 General Explanation 
3.1.1 Form of Input 


Input consists of text lines, which are destined to be printed, interspersed with control lines, which set pa- 
rameters or otherwise control subsequent processing. Control lines begin with a control character, normally a 
period or an acute accent, followed by a 1- or 2-character name that specifies a basic request or the substitution 
of a user-defined macro in place of the control line. The acute accent control character suppresses the break 
function (the forced output of a partially filled line) caused by certain requests. Control characters may be sepa- 
rated from request/macro names by white space (spaces and/or tabs) for esthetic reasons. Names must be fol- 
lowed by either a space or a newline character. Control lines with unrecognized request/macro names are 
ignored. Table 3.A is a cross reference of request names to the table in this section where an explanation of the 
request is displayed. 


Various special functions may be introduced anywhere in the input by means of an escape character (\). 
For example, the function \n R causes the interpolation of the contents of the number register Rin place of the 
function. Number register R is either an x for a single letter register name or (xx for a 2-character register 
name. Table 3.B itemizes escape sequences for characters, indicators, and functions. 


3.1.2 Formatter and Device Resolution 


The troff processor internally uses 432 units/inch, corresponding to the Wang Laboratories 
phototypesetter which has a horizontal resolution of 1/432 inch and a vertical resolution of 1/144 inch. It rounds 
horizontal/vertical numerical parameter input to the actual horizontal/vertical resolution of the typesetter. 


The nroff processor internally uses 240 units/inch, corresponding to the least common multiple of the hori- 
zontal and vertical resolutions of various typewriter-like output devices. It rounds numerical! input to the actual 
resolution of the output device indicated by the -T option (default Model 37 Teletype). 


3.1.3 Numerical Parameter Input 
Both nroff and troff formatters accept numerical input with the appended scale indicators shown in the 


following table, where Sis the current type size in points, Vis the current vertical line spacing in basic units, 
and Cis a nominal character width in basic units. 


NUMBER OF BASIC UNITS 
SCALE 
INDICATOR TROFF NROFF 


Inch 432 240 
Centimeter 432x50/127 | 240x50/127 
Pica = 1/6 inch 72 240/6 


em = S points 6xS C 

en = em/2 3xS C, same as em 
Point = 1/72 inch 6 240/72 

Basic unit 1 1 

Vertical line space V V 

Default (see following text) 
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In nroff processors, both em and en are taken to be equal to (, which is output-device-dependent; common 
values are 1/10. and 1/12 inch. Actual character widths in the nroff formatter need not be all the same. Con- 
structed characters (such as —>) are often extra wide. Default scaling is: 


e em for horizontally oriented requests (.ll, .in, .ti, .ta, .lt, .po, .me) and functions (\h, \). 

e V for vertically oriented requests (.pl, .wh, .ch, .dt, .sp, .sv, .ne, .rt) and functions (\v, \x, \L) 

e p for .vs request 

e u for .nr, .if, and .ie requests. 
All other requests ignore scale indicators. When a number register containing an already appropriately scaled 
number is interpolated to provide numerical input, the unit scale indicator (u) may need to be appended to pre- 
vent an additional inappropriate default scaling. The number, N, may be specified in decimal-fraction form but 


the parameter finally stored is rounded to an integer number of basic units. 


The absolute position indicator (1) may be prepended to a number Nto generate the distance to the vertical 
or horizontal place N. 


e For vertically oriented requests and functions, iN becomes the distance in basic units from the current 
vertical place on the page or in a diversion (paragraph 3.7) to the vertical place N. 


e For all other requests and functions, iN becomes the distance from the current horizontal place on the 
input line to the horizontal place N. 


For example 

Sp 13.2¢ 
will space in the required direction to 3.2 centimeters from the top of the page. 
3.1.4 Numerical Expressions 


Wherever numerical input is expected, an expression involving parentheses, the arithmetic operators +, — 

/, *, % (mod), and the logical operators <, >, <=, >=, = (or = =), & (and), : (or) may be used. Except where 

controlled by parentheses, evaluation of expressions is left to right; there is no operator precedence. In the case 

of certain requests, an initial + or — is stripped and interpreted as an increment or decrement indicator. In the 

presence of default scaling, the desired scale indicator must be attached to every number in an expression for 

which the desired and default scaling differ. For example, if the number register x contains 2 and the current 
point size is 10, then: 


ll (4.251+\nxP+3)/2u 
will set the line length to % the sum of 4.25 inches + 2 picas + 3 ems (80 points since the point size is 10). 
3.1.5 Notation 
Numerical parameters are indicated in this manual in two ways. A : Nmeans that the argument may take 
the forms N, +N, or —Nand that the corresponding effect is to set the affected parameter to N, to increment 
it by N, or to decrement it by N, respectively. Plain N means that an initial algebraic sign is not an increment 


indicator but merely the sign of N. Generally, unreasonable numerical input is either ignored or truncated to 
a reasonable value. For example, most requests expect to set parameters to non-negative values; exceptions are 
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Sp, .wh, .ch, .nr, and .if. The requests .ps, .ft, .po, .vs, .Is, ll, .in, and .It restore the previous parameter value 
in the absence of an argument. 


Single character arguments are indicated by single lowercase letters and 1- or 2-character arguments are 
indicated by a pair of lowercase letters. Character string arguments are indicated by multicharacter mnemon- 
ics. 


3.2 Font and Character Size Control 
3.2.1 Fonts 


Default mounted fonts are Times Roman (R), Times Italic (I), Times Bold (B), and Special Mathematical 
(S) on physical typesetter positions 1, 2, 3, and 4, respectively. These font styles are shown in Fig. 3.1. The cur- 
rent font, initially Times Roman, may be changed (among the mounted fonts) by use of the .ft request or by 
imbedding at any desired point either \fx, \f(xx, or \fN where x and xx are the name of a mounted font and 
Nisa numerical font position. It is not necessary to change to the Special Font; characters on that font are auto- 
matically handled. A request for a named but not mounted font is ignored. 


The troff processor can be informed that any particular font is mounted by use of the .fp request. The list 
of known fonts is installation dependent. In the subsequent discussion of font-related requests, F represents 
either a 1- or 2-character font name or the numerical font position, 1 through 4. The current font is available 
as numerical position in the read-only number register -f. 


Font control is understood by the nroff formatter which normally underlines italic characters. Table 3.C 
is a summary and explanation of font control requests. 


3.2.2 Character Set 


The troff character set consists of the so-called Commercial II character set plus a Special Mathematical 
font character set each having 102 characters. All ASCII characters are included with some on the Special Math- 
ematical font. The ASCII characters are input as themselves (with three exceptions); and non-ASCII characters 
are input in the form \(xx, where xxis a 2-character name given in Table 3.D. The three ASCII character exeep- 
tions are mapped as follows: 


acute accent 
grave accent 
minus 


The characters ; ‘, and — may be input by \’, \' , and \-, respectively, or by their names. The ASCII characters 
@,#",5',<>\,6},~™, *, and _ exist on the Special Mathematical font and are printed as a one em space 
if that font is not mounted. 


close quote 
open quote 
hyphen 


The nroff processor understands the entire troff character set but can print only: 
e ASCII characters 


e Additional characters as may be available on the output device 
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e Such characters as may be able to be constructed by overstriking or other combinations 
e Those characters that can reasonably be mapped into other printable characters. 


The exact behavior is determined by a driving table prepared for each device. The characters ‘*\and _ print 
as themselves. 


3.2.3 Character Size 


Character point sizes available are 6, 7, 8, 9, 10, 11, 12, 14, 16, 18, 20, 22, 24, 28, and 36. This is a range of 
1/12 inch to 1/2 inch. The .ps request is used to change or restore the point size. Alternatively, the point size 
may be changed between any two characters by imbedding a \sN at the desired point to set the size to Nor 
a\s+N(1 < N< 9) to increment/decrement the size by N; \sO restores the previous size. Requested point size 
values that are between two valid sizes yield the larger of the two. The current size is available in the .s number 
register. The nroff formatter ignores type size control. Table 3.E is a summary and explanation of character 
size requests. 


3.3 Page Control 


Top and bottom margins are not automatically provided. They may be defined by two macros which set traps 
at vertical positions 0 (top) and —N(N from the bottom). A pseudo-page transition onto the first page occurs 
either when the first break occurs or when the first nondiverted text processing occurs. Arrangements for a 
trap to occur at the top of the first page must be completed before this transition. A summary and explanation 
of page control requests is shown in Table 3.F. References to the current diversion mean that the mechanism 
being described works during both ordinary and diverted output (the former is considered as the top diversion 
level). 


Usable page width on the phototypesetter is about 7.54 inches. The left margin begins about 1/27 inch from 
the edge of the 8-inch wide, continuous roll paper. Physical limitations on the nroff processor output are output- 
device-dependent. 


3.4 Text Filling, Adjusting, and Centering 
3.4.1 Filling and Adjusting 


Normally, words are collected from input text lines and assembled into an output text line until some word 
does not fit. An attempt may be made to hyphenate the word in an effort to assemble a part of it into the output 
line. The spaces between the words on the output line are increased to spread out the line to the current line 
length minus any current indent. A word is any string of characters delimited by the space character or the 
beginning/end of the input line. Any adjacent pair of words that must be kept together (neither split across 
output lines nor spread apart in the adjustment process) can be tied together by separating them with the 
unpaddable space backslash-space character (\). The adjusted word spacings are uniform in the troff 
formatter, and the minimum interword spacing can be controlled with the .ss request. In the nroff formatter, 
they are normally nonuniform because of quantization to character-size spaces; however, the command line op- 
tion —e causes uniform spacing with full output device resolution. Filling, adjustment, and hyphenation can 
all be prevented or controlled. The text length on the last line output is available in the .n number register, and 
text base-line position on the page for this line is in the nl number register. The text base-line high-water mark 
(lowest place) on the current page is in the .h register. 


An input text line ending with ., ?, or! is taken to be the end of a sentence, and an additional space character 
is automatically provided during filling. Multiple interword space characters found in the input are retained, 
except for trailing spaces; initial spaces also cause a break. 


When filling is in effect, a \p escape sequence may be imbedded in or attached to a word to cause a break 
at the end of the word and have the resulting output line spread out to fill the current line length. 
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A text input line that happens to begin with a control character can be made not to look like a control line 
by prefacing it with the nonprinting, zero-width filler character (\&). Another way is to specify output transla- 
tion of some convenient character into the control character using the .tr request. 


3.4.2 Interrupted Text 
Copying of an input line in no-fill mode can be interrupted by terminating the partial line with a \e escape 
sequence. The next encountered input text line will be considered to be a continuation of the same line of input 
text. Similarly, a word within filled text may be interrupted by terminating the word (and line) with \e; the 
next encountered text will be taken as a continuation of the interrupted word. If the intervening control lines 
cause a break, any partial line will be forced out along with any partial word. 
Table 3.G is a summary and explanation of filling, adjusting, and centering requests. 
3.5 Vertical Spacing 
3.5.1 Base-line Spacing 
Vertical spacing size (V) between base lines of successive output lines can be set using the .vs request with 
a resolution of 1/144 inch = % point in the troff formatter and to the output device resolution in the nroff 
formatter. Spacing size must be large enough to accommodate character sizes on affected output lines. For the 
common type sizes (9 through 12 points), usual typesetting practice is to set V to two points greater than the 
point size; troff default is 10-point type on a 12-point spacing. The current V is available in the .v register. 
Multiple- V line separation (e.g., double spacing) may be obtained with a .Is request. 
3.5.2 Extra Line Space 
If a word contains a vertically tall construct requiring the output line containing it to have extra vertical 
space before and/or after it, the extra line space function \x’N’ can be imbedded in or attached to that word. 
In this and other functions having a pair of delimiters around their parameter, the delimiter choice is arbitrary 
except that it can not look like the continuation of a number expression for N. 
e If Nis negative, the output line containing the word will be preceded by N extra vertical spaces. 
e If Nis positive, the output line containing the word will be followed by N extra vertical spaces. 
e If successive requests for extra space apply to the same line, the maximum values are used. 
The most recently utilized post-line extra line space is available in the .a register. 


3.5.3 Blocks of Vertical Space 


A block of vertical space is ordinarily requested using .sp, which honors the no-space mode and which does 
not space past a trap. A contiguous block of vertical space may be reserved using the .sv request. 


Table 3.H is a summary and explanation of vertical spacing requests. 
3.6 Line Length and Indenting 

The maximum line length for fill mode may be set with a .l] request. The indent may be set with a .in re- 
quest; an indent applicable to only the next output line may be set with the .ti request. The line length includes 


indent space but not page offset space. The line length minus the indent is the basis for centering with the .ce 
request. If a partially collected line exists, the effect of .1I, .in, or .ti is delayed until after that line is output. 
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In fill mode, the length of text on an output line is less than or equal to the line length minus the indent. The 
current line length and indent are available in registers .] and .i, respectively. The length of 3-part titles pro- 
duced by .tl is independently set by .1t. Table 3.1 is a summary and explanation of line length and indenting re- 
quests. 
3.7 Macros, Strings, Diversions, and Position Traps 
3.7.1 Macros and Strings 

A macro is a named set of arbitrary lines that may be invoked by name or with a trap. A string is a named 
string of characters, not including a newline character, that may be interpolated by name at any point. Request, 
macro, and string names share the same name list. Macro and string names may be 1- or 2-characters long and 
may usurp previously defined request, macro, or string names. Any of these entities may be renamed with .rn 
or removed with .rm. 


e Macros are created by .de and .di and appended by .am and .da (.di and .da cause normal output to 
be stored in a macro) 


e Strings are created by .ds and appended by .as. 
A macro is invoked in the same way as a request; a control line beginning .xx will interpolate the contents of 
macro xx. The remainder of the line may contain up to nine arguments. The strings x and xx are interpolated 
at any desired point with \*x and \*( xx, respectively. String references and macro invocations may be nested. 


3.7.2 Copy Mode Input Interpretation 


During the definition and extension of strings and macros (not by diversion), the input is read in copy mode. - 
The input is copied without interpretation except that: 


e Contents of number registers indicated by \n are interpolated. 

e Strings indicated by \* are interpolated. 

e Arguments indicated by \$ are interpolated. 

e Concealed newline characters indicated by \<newline> are eliminated. 

e Comments indicated by \" are eliminated. 

e \t and \a are interpreted as ASCII horizontal tab and start of heading (SOH), respectively (Part 9). 
e \\ is interpreted as “\”. 


e \. is interpreted as “.”. 


These interpretations can be suppressed by prepending a \. For example, since \\ maps into a \, \\n will copy 
as \n which will be interpreted as a number register indicator when the macro or string is reread. 


3.7.3 Arguments 
When a macro is invoked by name, the remainder of the line may contain up to nine arguments. The argu- 


ment separator is the space character, and arguments may be surrounded by double-quotes to permit imbedded 
space characters. Pairs of double-quotes may be imbedded in double-quoted arguments to represent a single 
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double-quote. If the desired arguments will not fit on a line, a concealed newline character may be used to con- 
tinue on the next line. 


When a macro is invoked, the input level is pushed down and any arguments available at the previous level 
become unavailable until the macro is completely read and the previous level is restored. A macro’s own argu- 
ments can be interpolated at any point within the macro with \$N, which interpolates the Mth argument (1 


< N< 9). If an invoked argument does not exist, a null string results. For example, the macro xx may be defined 
by 


de xx \" begin definition 
Today is \\$1 the \\$2. 

5 \" end definition 
and called by 


.xx Monday 14th 
to produce the text 
Today is Monday the 14th. 


The \$ was concealed in the definition with a prepended \. The number of currently available arguments is 
in the .$ register. 


No arguments are available at the top (nonmacro) level in this implementation. Because string referencing 
is implemented as an input-level pushdown, no arguments are available from within a string. No arguments 
are available within a trap-invoked macro. 


Arguments are copied in copy mode onto a stack where they are available for reference. The mechanism 
does not allow an argument to contain a direct reference to a long string (interpolated at copy time), and it is 
advisable to conceal string references (with an extra \) to delay interpolation until argument reference time. 


3.7.4 Diversions 

Processed output may be diverted into a macro for purposes such as footnote processing or determining the 
horizontal and vertical size of some text for conditional changing of pages or columns. A single diversion trap 
may be set at a specified vertical position. The number registers .dn and .dl, respectively, contain the vertical 
and horizontal size of the most recently ended diversion. Processed text that is diverted into a macro retains 
the vertical size of each of its lines when reread in no-fill mode regardless of the current V. Constant-spaced 
(.cs) or emboldened (.bd) text that is diverted can be reread correctly only if these modes are again or still in 
effect at reread time. One way to do this is to imbed in the diversion the appropriate .es or .bd request with 
the transparent mechanism described in paragraph 3.10.6. 


Diversions may be nested and certain parameters and registers are associated with the current diversion 
level (the top non-diversion level may be thought of as diversion level 0). These parameters and registers are: 


e diversion trap and associated macro 

e no-space mode 

e internally saved marked place (see .mk and .rt) 
e current vertical place (.d register) 


e current high-water text base line (.h register) 
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e® current diversion name (.z register). 
3.7.5 Traps 
Three types of trap mechanisms are available: 
® page trap 
e diversion trap 
e input-line-count trap. 


Macro-invocation traps may be planted using .wh requests at any page position including the top. This trap 
position may be changed using .ch. Trap positions at or below the bottom of the page have no effect unless or 
until moved to within the page or rendered effective by an increase in page length. Two traps may be planted 
at the same position only by first planting them at different positions and then moving one of the traps; the 
first planted trap will conceal the second unless and until the first one is moved. If the first planted trap is 
moved back, it again conceals the second trap. The macro associated with a page trap is automatically invoked 
when a line of text is output whose vertical size reaches or sweeps past the trap position. Reaching the bottom 
of a page springs the top-of-page trap, if any, provided there is a next page. The distance to the next trap position 
is available in the .t register; if there are no traps between the current position and the bottom of the page, the 
distance returned is the distance to the page bottom. 


Macro-invocation traps, effective in the current diversion, may be planted using .dt requests. The .t register 
works in a diversion. If there is no subsequent trap, a large distance is returned. 


Table 3.J is a summary and explanation of macros, strings, diversion, and position traps requests. 


3.8 Number Registers 


A variety of predefined number registers (Table 3.K) are available to the user. In addition, the user may 
define his own named registers. Register names are 1- or 2-characters long and do not conflict with request, 
macro, or string names. Except for certain predefined read-only number registers (Table 3.L), a number register 
can be read, written, automatically incremented or decremented, and interpolated into the input in a variety 
of formats. One common use of user-defined registers is to automatically number sections, paragraphs, lines, 
etc. A number register may be used any time numerical input is expected or desired and may be used in numeri- 
cal expressions. 


Number registers are created and modified using the .nr request, which specifies name, numerical value, 
and automatic increment size. Registers are also modified if accessed with an automatic incrementing sequence. 
If the registers xand xx both contain Nand have the automatic increment size M, the following access sequences 


have the effect shown as follows: 
EFFECT ON VALUE 
REGISTER INTERPOLATED 
nx none N 


n( xx none N 
nt+x xX incremented by M N+M 


x decremented by M 
xx incremented by M 
xx decremented by M 
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to: 


e decimal (default) 


e decimal with leading zeros 


e e lowercase Roman 


uppercase Roman 


e lowercase sequential alphabetic 
@ uppercase sequential alphabetic. 
é Table 3.M is a summary and explanation of number registers requests. 
3.9 Tabs, Leaders, and Fields 
3.9.1 Tabs and Leaders 
The ASCII horizontal tab character and the ASCII SOH character (the leader) can both be used to generate 

either horizontal motion or a string of repeated characters. The length of the generated entity is governed by 
internal tab stops specified with a .ta request. The default difference is that tabs generate motion and leaders 


generate a string of periods; .te and .Ic offer the choice of repeated character or motion. There are three types 
of internal tab stops: left justified, right justified, and centered. In the following table: 


e next-string consists of the input characters following the tab (or leader) up to the next tab (or leader) 
& or end of line 


e Dis the distance from the current position on the input line (where a tab or leader was found) te the 
next tab stop 


e Wis the width of next-string. 


TAB LENGTH OF MOTION OR LOCATION OF 
TYPE REPEATED CHARACTERS next-string 
D 


Left 
@& Right D-W Right justified within D 
Centered D-W/2 Centered on right end of D 


Following D 


The length of generated motion is allowed to be negative but that of a repeated character string cannot be. 
Repeated character strings contain an integer number of characters, and any residual distance is prepended 
as motion. Tabs (or leaders) found after the last tab stop are ignored, but they may be used as next-string termi- 


& nators. 


Tabs and leaders are not interpreted in copy mode. The \t and \a always generate a noninterpreted tab 
and leader, respectively, and are equivalent to actual tabs and leaders in copy mode. 
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According to the format specified by the .af request, a number register is converted (when interpolated) 
: 
; 


DOCUMENT PROCESSING GUIDE ISSUE 1 6/82 


3.9.2 Fields 


A field is contained between a pair of,field delimiter characters. It consists of substrings separated by pad- 
ding indicator characters. The field length is the distance on the input line from the position where the field 
begins to the next: tab stop. The difference between the total length of all the substrings and the field length 
is incorporated as horizontal padding space that is divided among the indicated padding places. The incorpo- 
rated padding is allowed to be negative. For example, if the field delimiter is # and the padding indicator is 
“, then #*xxx* right # specifies a right-justified string with the string xxx centered in the remaining space. 


’ 


Table 3.N is a summary and explanation of tab, leader, and field requests. 
3.10 Input/Output Conventions and Character Translations 


3.10.1 Input Character Translations 


The newline character delimits input lines. In addition, STX, ETX, ENQ, ACK, and BEL are accepted and 
may be used as delimiters or translated into a graphic with a .tr request. All others are ignored. 


The escape character (\) introduces sequences that cause the following character to mean another character 
or to indicate some function. A complete list of such sequences is given in Table 3.B. The escape character: 


e should not be confused with the ASCII control character ESC of the same name 
e can be input with the sequence \\ 


e can be changed with .ec, and all that has been said about the default \ becomes true for the new escape 
character. 


A \e sequence can be used to print the current escape character. If necessary or convenient, the escape mecha- 
nism may be turned off with .eo and restored with .ec. A summary and explanation of input character transla- 
tions requests are contained in Table 3.0. 


3.10.2 Ligatures 


Five ligatures are available in the troff character set: fi, fl, ff, ffi, and fl. They may be input (even in the nroff 
formatter) by \(fi, \(fl, \(ff, \(Fi, and \(FI, respectively. The ligature mode is normally on in the troff 
formatter and automatically invokes ligatures during input. A summary and explanation of ligature requests 
are included in Table 3.0. 


3.10.3 Backspacing, Underlining, and Overstriking 


Unless in copy mode, the ASCII backspace character is replaced by a backward horizontal motion having 
the width of the space character. Underlining as a form of line drawing and, as a generalized overstriking func- 
tion, is described in Part 12. 


The nroff processor underlines characters automatically in the underline font, specifically with the .uf re- 
quest. The underline font is normally on font position 2 (Times Italic). In addition to .ft request and \fF escape 
sequence, the underline font may be selected by .ul and .cu requests. Underlining is restricted to an output- 
device-dependent subset of reasonable characters. A summary and explanation of backspacing, underlining, and 
overstriking requests are included in Table 3.0. : 


3.10.4 Control Characters 


Both the break control character (.) and the (no-break) control character ’ may be changed, if desired. Such 
a change must be compatible with the design of any macros used in the span of the change and particularly of 
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any trap-invoked macros. A summary and explanation of the .ce and .c2 control character requests are included 
in Table 3.0. 


3.10.5 Output Translation 


One character can be made a stand-in for another character using the .tr request. All text processing (e.g., 
character comparisons) takes place with the input (stand-in) character which appears to have the width of the 
final character. Graphic translation occurs at the moment of output (including diversion). Included in Table 3.0 
is a summary and explanation of the output translation request. 


3.10.6 Transparent Throughput 

An input line beginning with a \! is read in copy mode and transparently output (without the initial \!); 
the text processor is otherwise unaware of the line’s presence. This mechanism may be used to pass control in- 
formation to a post-processor or to imbed control lines in a macro created by a diversion. 
3.10.7 Comments and Concealed Newline Characters 

An uncomfortably long input line that must stay one line (e.g., a string definition or no-filled text) can be 
split into many physical lines by ending all but the last one with the escape \. The sequence \<newline> is ig- 
nored except in a comment. Comments may be imbedded at the end of any line by prefacing them with \". 


The newline character at the end of a comment cannot be concealed. A line beginning with \" will appear as 
a blank line and behave like .sp 1; a comment can be on a line by itself by beginning the line with .\". 


3.11 Local Horizontal/Vertical Motion and Width Function 
3.11.1 Local Motion 

The functions \v’N’ and \h’N’ can be used for local vertical and horizontal motion, respectively. The dis- 
tance N may be negative; the positive directions are rightward and downward. A local motion is one contained 
within a line. To avoid unexpected vertical dislocations, it is necessary that the net vertical local motion (within 
a word in filled text and otherwise within a line) balance to zero. The above and certain other eseape sequences 
providing local motion are summarized and explained in Table 3.P. As an example, E2 is generated by the se- 
quence E\v’—0.5’\s—4\&2\s0\v’0.5’, 

3.11.2 Width Function 

The width function \w’string’ generates the numerical width of string (in basic units). Size and font 
changes may be imbedded in string and will not affect the current environment. For example, .ti-\w’1u could 
be used to temporarily indent leftward a distance equal to the size of the string ‘‘1.”. 

The width function also sets three number registers. The registers st and sb are set respectively to the 
highest and lowest extent of string relative to the baseline; then, for example, the total height of the string is 
\n(stu—\n(sbu. In the troff formatter, the number register ct is set to a value between 0 and 3: 

e O means that all characters in string are short lowercase characters without descenders (like e) 
e 1 means that at least one character has a descender (like y) 


e 2 means that at least one character is tall (like H) 


e 3 means that both tall characters and characters with descenders are present. 
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3.11.3 Mark Horizontal Place 

The escape sequence \kx will cause the current horizontal position in the input line to be stored in register 
x. As an example, the construction \kx word\h’\nxu+ 2u’ word will embolden word by backing up almost to 
its beginning and overprinting it, resulting in word. 
3.12 Overstrike, Zero-Width, Bracket, and Line Drawing Functions 
3.12.1 Overstrike 

Automatically centered overstriking of up to nine characters is provided by the overstrike function 

\o’string’. 


Characters in string are overprinted with centers aligned; the total width is that of the widest character. The 
string should not contain local vertical motion. As examples, \o’e\” produces é, and \o’>/’ produces #. 


3.12.2 Zero-Width Characters 

The function \zc will output c without spacing over it and can be used to produce left-aligned overstruck 
combinations. As examples, \z\(ci\(pl will produce ®, and \(br\z\(rn\(ul\(br will produce the smallest 
possible constructed box. 
3.12.3 Large Brackets 

The Special Mathematical Font contains a number of bracket construction pieces that can be combined into 
various bracket styles. The function \b’string’ may be used to pile up vertically the characters in string (the 
first character on top and the last at the bottom); the characters are vertically separated by one em and the 
total pile is centered one-half em above the current base line (one-half line in the nroff formatter). For example: 


\b’\(le\Uf’E\\b’\(re\(rf’\x’—0.5m’\x’0.5m’ 


produces: 


Le | 
3.12.4 Line Drawing 


The function \I’Ne’ will draw a string of repeated c’s toward the right for a distance N (lis lowercase 
L). 


e If clooks like a continuation of an expression for N, it may be insulated from N with a \&. 
e If cis not specified, the base-line rule (_) is used (underline character in nroff). 
e If Nis negative, a backward horizontal motion of size Nis made before drawing the string. 


Any space resulting from N/(size of c) having a remainder is put at the beginning (left end) of the string. In 
the case of characters that are designed to be connected, such as base-line rule (_), underrule (\(ul), and root 
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en (\(ru), the remainder space is covered by overlapping. If Nis less than the width of ¢ a single cis centered 
on a distance N. As an example, a macro to underscore a string can be written 


.de us 


\\$1\110\(ul’ 


or one to draw a box around a string: 


.de bx 
\(br\\\$1\i\(br\0\(rn’ \V10\(ul’ 


such that 
€ us “underlined words” 
and 
.bx “words in a box” 
yield 
underlined words 
and 


e words in a box 


The function \L’ Ne’ will draw a vertical line consisting of the optional character c stacked vertically apart 
one em (one line in nroff), with the first two characters overlapped, if necessary, to form a continuous line. The 
default character is box rule (\(br); the other suitable character is bold vertical (\(bv). The line is begun with- 
out any initial motion relative to the current base line. A positive N specifies a line drawn downward, and a 
negative N specifies a line drawn upward. After the line is drawn, no compensating motions are made; the in- 
stantaneous base line is at the end of the line. 


The horizontal and vertical line drawing functions may be used in combination to produce large boxes. The 
zero-width box-rule and the one-half em wide underrule were designed to form corners when using one em verti- 


€ cal spacings. For example, the macro 
.de eb 
.sp—l \" compensate for next automatic base-line spacing 
nf \" avoid possibly overflowing word buffer 


\h’—.5n’\L7\\nau-1’\l’\\nClutin\(ul\L’—1\\nautl\V0u—.5n\ 
\(ul’ \" draw box 
fi 
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will draw a box around some text whose beginning vertical place was saved in number register a (e.g., using 
-mk a). 


3.13 Hyphenation 


The automatic hyphenation may be switched off and on. When switched on with -hy, several variants may 
be set. A hyphenation indicator character may be imbedded in a word to specify desired hyphenation points or 
may be prepended to suppress hyphenation. In addition, the user may specify a small exception word list. The 
default condition of hyphenation is off. 


Only words that consist of a central alphabetic string surrounded by nonalphabetic strings (usually null) 
are considered candidates for automatic hyphenation. Words that were input containing hyphens (minus), em- 
dashes (\(em), or hyphenation indicator characters (such as mother-in-law) are always subject to splitting 
after those characters whether or not automatic hyphenation is on or off. Table 3.Q is a summary and explana- 
tion of hyphenation requests. 


3.14 Three-Part Titles 

The titling function .tl provides for automatic placement of three fields at the left, center, and right of a 
line with a title length specifiable with .Jt. The .t] may be used anywhere and is independent of the normal text 
collecting process. A common use is in header and footer macros. Table 3.R is a summary and explanation of 
3-part title requests. 
3.15 Output Line Numbering 


Automatic sequence numbering of output lines may be requested with .nm. When in effect, a 3-digit, Arabic 
number plus a digit-space is prepended to output text lines. Text lines are offset by four digit-spaces and other- 
wise retain their line length. A reduction in line length may be desired to keep the right margin aligned with 
an earlier margin. Blank lines, other vertical spaces, and lines generated by .tl are not numbered. Numbering 
can be temporarily suspended with .nn or with a .nm followed by a later .nm +0. In addition, a line number 
indent J and the number-text separation S may be specified in digit-spaces. Further, it can be specified that 
only those line numbers that are multiples of some number Mare to be printed (the others will appear as blank 
number fields). Table 3.8 is a summary and explanation of output line numbering requests. 

Figure 3.2 is an example of output line numbering. Paragraph portions are numbered with M=3: 

e .nm 1 3 was placed at the beginning; 

e .om +0 was placed in front of the second paragraph; 

e and .nm was placed at the end. 
Line lengths were also changed (by \w’0000’u) to keep the right side aligned. Another example is .nm +5 5 
x 3, which turns on numbering with the line number of the next line to be five greater than the last numbered 
line, with M=5, spacing S untouched, and the indent I set to 3. 
3.16 Conditional Acceptance of Input 

In Table 3.T, which is a summary and explanation of conditional acceptance requests: 
e cis a 1-character, built-in condition name. 


e ! signifies not. 


e Nis a numerical expression. 
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e string] and string2 are strings delimited by any nonblank, nonnumeric character not in the strings. 
e anything represents what is conditionally accepted. 


Built-in condition names are: 


CONDITION 
NAME 


Current page number is odd 
Current page number is even 
Formatter is troff 
Formatter is nroff 


If condition cis true, if number Nis greater than zero, or if strings compare identically (including motions and 
character size and font), anything is accepted as input. If a! precedes the condition, number, or string compari- 
son, the sense of the acceptance is reversed. 


Any spaces between the condition and the beginning of anything are skipped over. The anything can be ei- 
ther a single input line (text, macro, or whatever) or a number of input lines. In the multiline case, the first 
line must begin with a left delimiter \{ and the last line must end with a right delimiter \}. 


The request .ie (if-else) is identical to .if except that the acceptance state is remembered. A subsequent and 
matching .el (else) request then uses the reverse sense of that state. The .ie—.el pairs may be nested. For exam- 
ple: 


99 


if e tl’ Even Page % 
outputs a title if the page number is even, and 


ie\n% >1\{\ 
’sp 0.51 

.ti Page %’” 
’spll.2i\} 


.el .spi2.5i 
treats page 1 differently from other pages. 
3.17 Environment Switching 


A number of parameters that control text processing are gathered together into an environment, which can 
be switched by the user. Environment parameters are those associated with some requests. The tables at the 
end of this section indicate in the “Explanation” column those requests so affected. In addition, partially col- 
lected lines and words are in the environment. Everything else is global; examples are page-oriented parame- 
ters, diversion-oriented parameters, number registers, and macro and string definitions. All environments are 
initialized with default parameter values. Table 3.U is a summary and explanation of the environment switching 
request. 


3.18 Insertions From Standard Input 


The input can be switched temporarily to the system standard input with .rd and switched back when two 
newline characters in a row are found (the extra blank line is not used). This mechanism is intended for inser- 
tions in form-letter-like documentation. On the UNIX operating system, the standard input can be the user key- 
board, a pipe, or a file. 


Page 71 


DOCUMENT PROCESSING GUIDE ISSUE 1 6/82 


If insertions are to be taken from the terminal keyboard while output is being printed on the terminal, the 
command line option —q will turn off the echoing of keyboard input and prompt only with BEL. The regular 
input and insertion input cannot simultaneously come from the standard input. As an example, multiple copies 
of a form letter may be prepared by entering insertions for all copies in one file to be used as the standard input 
and causing the file containing the letter to reinvoke itself by using the .nx request. The process would be ended 
by a.ex request in the insertion file. 


Table 3.V is a summary and explanation of insertions from the standard input requests. 
3.19 Input/Output File Switching 

Table 3.W is a summary and explanation of input/output file switching requests. 
3.20 Miscellaneous 

Table 3.X is a summary and explanation of miscellaneous requests. 
3.21 Output and Error Messages 


Output from .tm, .pm, and prompt from .rd, as well as various error messages are written onto the UNIX 
operating system standard message output. The latter is different from the standard output, when compared 
to the nroff formatted output. By default, both are written onto the user’s terminal, but they can be indepen- 
dently redirected. : 


Various error conditions may occur during the operation of the nroff and troff formatters. Certain less 
serious errors having only local impact do not cause processing to terminate. Two examples are: 


e word overflow—caused by a word that is too large to fit into the word buffer (in fill mode) 
e line overflow—caused by an output line that grew too large to fit in the line buffer. 


In both cases, a message is printed, the offending excess is discarded, and the affected word or line is marked 
at the point of truncation with a * (in nroff) or a <right hand» (in troff). The philosophy is to continue process- 
ing, if possible, on the grounds that output useful for debugging may be produced. If a serious error occurs, pro- 
cessing terminates, and an appropriate message is printed. Examples are the inability to create, read, or write 
files, and the exceeding of certain internal limits that make future output unlikely to be useful. 


Table 3.Y is a summary and explanation of output and error messages requests. 
3.22 Compacted Macros 


The time required to read a macro package by the nroff formatter may be lessened by using a compacted 
macro (a preprocessed version of a macro package). The compacted version is equivalent to the noncompacted 
version, except that a compacted macro package cannot be read by the .so request. A compacted version of a 
macro package, called name, is used by the -cname command line option, while the uncompacted version is used 
by the -m name option. Because —ename defaults to -mnameif the name macro package has not been compact- 
ed, the user should always use —e rather than —m. 


3.22.1 Building a Compacted Macro Package 


Only macro, string, and diversion definitions; number register definitions and values; environment settings; 
and trap settings can be compacted. End macro (em) requests and any commands that may interact during 
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package interpretation with command-line settings (such as references in the MM macro package to the number 
register P, which can be set from the command line) are not compactible. There are two steps to make a com- 
pacted macro from a macro package: 


e Separate compactible from noncompactible parts 


e Place noncompactible material at the end of the macro package with a .co request. The .co request indi- 
cates to the nroff formatter when to compact its current internal state. 


Compactible Material 


.cO 
Noncompactible Material 


3.22.2 Produce Compacted Files 


When compactible and noncompactible segments have been established, the nroff formatter may be run 
with the —k option to build the compacted files. For example, if the output file to be produced is called mac, 
the following may be used to build the compacted files: 


nroff —kmac mac 


This command causes the nroff formatter to create two files in the current directory, d.mac and t.mac. The 
macro file must contain a .co request. Only lines before the .co request will be compacted. Both —k and .co are 
necessary. If no .co is found in the file, the —k is ignored. Likewise, if no —k appears on the command line, the 
.co is ignored. 


Each macro package must be compacted separately by the nroff formatter. Compacted macro packages de- 
pend on the particular version of the nroff formatter that produced them. Any compacted macro packages must 
be recompacted when a new version of an nroff formatter is installed. If it is discovered that a macro package 
was produced by a different version than that attempting to read it, the —e will be abandoned, and the equiva- 
lent —m option attempted instead. 


3.22.3 Install Compacted Files 
The two compacted files, d.macand t.mae, must be installed in the system macro library (/usr/lib/macros) 

with the proper names. If the files were produced by an nroff formatter, emp.n. must be prepended to their 
names. For example, if the macro package is called mac, the two nroff formatter compacted files may be in- 
stalled by 

cp d.mac /usr/lib/macros/emp.n.d.mac 
or 

cp t.mac /usr/lib/macros/cmp.n.t.mac 
3.22.4 Install Noncompactible Segment 


The noncompactible segment from the original macro package must be installed on the system as 


/usr/lib/macros/ucmp.[nt].mac 
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where n of [nt] means the nroff formatter version, and t means the troff formatter version. The 
noncompactible segment must be produced manually by using the editor. Using the mac package as an example, 
the following could be used to install the nroff formatter noncompactible segment: 


$ ed mac 
/*\.co$/+,$w /usr/lib/macros/ucmp.n.mac 


4. TROFF Tutorial 
4.1 Overview 


An important rule of using the troff formatter is to use it through an intermediary. In many ways the troff 
formatter resembles an assembly language, remarkably powerful and flexible, but nonetheless such that many 
operations must be specified at a level of detail and in a form that is too difficult for most people to use effective- 


ly. 


There are programs that provide an interface to the troff formatter for the majority of users for two special 
applications. 


e The eqn program provides an easy to learn language for typesetting mathematics. The user does not 
need to know the troff formatter to typeset mathematics. 


e The tbl program provides the same convenience for producing tables of arbitrary complexity. 


For producing text that may contain mathematics or tables, there are a number of macro packages that 
define formatting rules and operations for specific styles of documents and reduce the amount of direct contact 
with the troff formatter. In particular, the Memorandum Macros (MM) package provides most of the facilities 
needed for a wide range of document preparation. There are also packages for viewgraphs and other special ap- 
plications. These packages are easier to use than the troff formatter once the user gets beyond the most trivial 
operations. They should be considered first. 


In the few cases where existing packages do not accomplish the job, the solution is not to write an entirely 
new set of troff instructions from scratch but to make small changes to adapt packages that already exist. In 
accordance with this philosophy, the part of the troff formatter described here is only a small part of the whole, 
although it tries to concentrate on the more useful parts. The emphasis is on doing simple things and making 
incremental changes to what already exists. The troff formatter described is the C language version running 
on the UNIX operating system at Murray Hill. 


To use the troff formatter, the actual text must be prepared plus some information that describes how it 
is to be printed. Text and formatting information are intimately intertwined. Most commands to the troff 
formatter are placed on a line separate from the text itself, one command per line beginning with a period. For 
example 


Some text. 
ps 14 
Some more text. 


will change the point size of the letters being printed to 14 point (one point is 1/72 of an inch), 


Occasionally, something special occurs in the middle of a line, such as an exponent. The formula for the area 
of a circle ig typed as follows: 


Area = \(*p\fIr\fR\\s8\u2\d\s0 


The backslash character (\) is used to introduce troff commands and special characters within a line of text. 


Page 74 


